feat: Add docs for third party OIDC providers #1769

Nikpolik · 2024-12-04T13:38:02Z

Important

🔎 Previews:

This PR:

Adds instructions on how to configure any OIDC compatible OAuth provider to be used with enterprise_sso and enterprise_connections.

Also updated the overview to have an OIDC section similar to SAML that mentions EASIE and custom OAuth providers as an alternative.

Checklist

I have clicked on "Files changed" and performed a thorough self-review
I have added the "deploy-preview" label and added the preview link(s) to this PR description
All existing checks pass

Note

Opened PR to change title to "Third Party" and fix OIDC abbreviation
Need to also update /authentication/social-connections/custom-provider doc re: manual configuration section

github-actions · 2024-12-04T13:38:18Z

Hey, here’s your docs preview: https://clerk.com/docs/pr/1769

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

victoriaxyz · 2024-12-05T21:23:06Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

+  1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+  1. Select **Add connection** and select **For specific domains**.
+  1. Under **Third party**, select **OIDC**.
+  1. Add the **Name** of the connection.
+  1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation).
+  1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.
+  1. Select **Add connection**. You will be redirected to the connection's configuration page.
+
+  The next steps involve configuring both your Identity Provider (IdP) and Clerk. Keep both dashboards open as you'll need to reference them.


Suggested change

1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.

1. Select **Add connection** and select **For specific domains**.

1. Under **Third party**, select **OIDC**.

1. Add the **Name** of the connection.

1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation).

1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.

1. Select **Add connection**. You will be redirected to the connection's configuration page.

The next steps involve configuring both your Identity Provider (IdP) and Clerk. Keep both dashboards open as you'll need to reference them.

1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.

1. Select **Add connection** and select **For specific domains**.

1. Under **Or connect a third party**, select **OIDC (OpenID Connect)**.

1. Enter the **Name** of the connection.

1. Enter the **Key** of the provider. This is the provider's unique identifier which cannot be changed after creation.

1. Enter the **Specific Domain**. This is the domain of the users you want to allow to sign in to your app.

1. Select **Add connection**. You'll be redirected to the connection's configuration page. Keep this page open.

@Nikpolik where do users get the oauth_custom_ key? What's an example?

It's up to them to set something so they can know from which connection each user was created!

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

…le-feature

victoriaxyz · 2024-12-05T22:00:31Z

@Nikpolik, the docs are looking good. I'd love to see an example connection setup.

Nikpolik · 2024-12-06T11:39:35Z

@victoriaxyz I dm'd you the credentials for a dummy microsoft provider I have setup if you want to test this! Ping me if you want to look at this together!

…ibutes

…le-feature

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

…r.mdx

alexisintech

LGTM! Thank you so much 😸💖

victoriaxyz · 2024-12-09T20:55:14Z

Thanks for pairing with me to test this, @Nikpolik! :)

Please feel free to change or edit the updates I added:

We should also update the SSO connection custom provider doc to match the following update in this doc:

Most IdPs provide a Discovery Endpoint to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select Use Manual Configuration in the Identity Provider Configuration section to manually configure the connection.

cc: @alexisintech

alexisintech · 2024-12-09T22:17:48Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

  ### Configure your IdP

  1. If necessary, create a new app in your IdP.
-  1. In the connection's configuration page in the Clerk Dashboard, copy the **Authorized redirect URI**.
+  1. In the Clerk Dashboard, navigate to the connection's settings page.


they should already be there according to the last step in the previous step. so the copy before was correct

Adjusted steps 1 and 2 to make this a bit more clear 8f754cb.

Also moved the discovery endpoint explanation to a Note so we can have all the required steps uninterrupted.

WDYT?

alexisintech · 2024-12-09T22:18:49Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

-  1. Add the minimum required scopes based on the IdP's documentation. Common OIDC scopes include `openid`, `email`, and `profile`.
+  Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select **Use Manual Configuration** in the **Identity Provider Configuration** section to manually configure the connection.
+
+  1. In the Clerk Dashboard, navigate to the connection's settings page.


You wouldn't get the client ID and client secret in the clerk dashboard. you would get those from your IdP and then paste them in the clerk dashboard. so i believe the copy before was correct

alexisintech · 2024-12-09T22:19:50Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

  1. Select **Save**.

  ### Configure attribute mapping (optional)

-  If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. Important Clerk user properties include `email`, `firstName`, and `lastName`.
+  Attribute mapping allows you to map the IdP's claims with Clerk's user properties such as the `email_verified`. OIDC Enterprise connections require the [`email_verified` claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format.


Suggested change

Attribute mapping allows you to map the IdP's claims with Clerk's user properties such as the `email_verified`. OIDC Enterprise connections require the [`email_verified` claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format.

Attribute mapping allows you to map the IdP's claims with Clerk's user properties. OIDC enterprise connections require the [`email_verified` claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format.

Changed this section to be more similar to it's previous form 07e1f1a

It's not required for most users so I think keeping it brief is better to avoid confusion 🙂

alexisintech · 2024-12-09T22:20:10Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

+  1. In the Clerk Dashboard, navigate to the **Connection** tab of the connection's settings page.
+  1. In the **Attribute Mapping** section, under the **Email address verified** field:
+
+  - If the IdPs that provide the value, enter `email_verified`.


Suggested change

- If the IdPs that provide the value, enter `email_verified`.

- If the IdP provides the value, enter `email_verified`.

alexisintech · 2024-12-09T22:22:59Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

+  1. In the Clerk Dashboard, navigate to the **Connection** tab of the connection's settings page.
+  1. In the **Attribute Mapping** section, under the **Email address verified** field:


Suggested change

1. In the Clerk Dashboard, navigate to the **Connection** tab of the connection's settings page.

1. In the **Attribute Mapping** section, under the **Email address verified** field:

1. In the connection's settings page in the Clerk Dashboard, under **Attribute Mapping**, for the **Email address verified* field:

alexisintech · 2024-12-09T22:26:00Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

+  1. In the **Attribute Mapping** section, under the **Email address verified** field:
+
+  - If the IdPs that provide the value, enter `email_verified`.
+  - For IdPs that do not provide the value, enter `xms_edov`.


let's use the same syntax as the sentence before, and use a contraction!

Suggested change

- For IdPs that do not provide the value, enter `xms_edov`.

- If the IdP doesn't provide the value, enter `xms_edov`.

If it's ok, I removed this part as it is to specific to Microsoft!

alexisintech · 2024-12-09T22:31:10Z

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

-  > [!CAUTION]
-  > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. If the IdP doesn't return this claim, you can set its default value of `true`. However, ensure you fully trust the IdP to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth).
+  > [!WARNING]
+  > If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).


this step mentions that the user should set the default value to true whether the idp returns the claim or not. but then this callout says the user should only do it if the idp doesn't return the claim. which is the correct case so we can update accordingly?

Suggested change

> If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).

> If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to **True**. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).

yes, the way you've rewritten it makes a lot more sense!

alexisintech

looks awesome!! 😸💖

Co-authored-by: victoria <[email protected]> Co-authored-by: Alexis Aguilar <[email protected]>

Nikpolik added the deploy-preview label Dec 4, 2024

Nikpolik self-assigned this Dec 4, 2024

Nikpolik force-pushed the nikpolik/user-1107-write-docs-on-how-to-enable-feature branch from cbd1cc6 to e837507 Compare December 4, 2024 13:40

feat: Add docs for third party OIDC providers

7640084

Nikpolik force-pushed the nikpolik/user-1107-write-docs-on-how-to-enable-feature branch from e837507 to 7640084 Compare December 4, 2024 13:41

Nikpolik marked this pull request as ready for review December 4, 2024 13:42

Nikpolik requested a review from a team as a code owner December 4, 2024 13:42

victoriaxyz reviewed Dec 5, 2024

View reviewed changes

Merge branch 'main' into nikpolik/user-1107-write-docs-on-how-to-enab…

bf382a9

…le-feature

Apply suggestions from code review

b340a99

Nikpolik and others added 10 commits December 6, 2024 13:43

Fix linter complaint

42c1e83

add test connection section; add suggestions for important clerk attr…

3f9119b

…ibutes

Merge branch 'main' into nikpolik/user-1107-write-docs-on-how-to-enab…

980ab36

…le-feature

delevel heading for reading clarity

f8e51db

add sentence about different protocols

d4effe8

Merge branch 'main' into nikpolik/user-1107-write-docs-on-how-to-enab…

89997c5

…le-feature

format

fcc2bcb

fix terms and add link to OIDC

ca4b41f

use IdP abbreviation

641d747

update instructions to allow additional identifiers

a768763

alexisintech reviewed Dec 9, 2024

View reviewed changes

docs/authentication/enterprise-connections/oidc/custom-provider.mdx Outdated Show resolved Hide resolved

Update docs/authentication/enterprise-connections/oidc/custom-provide…

2277b8c

…r.mdx

alexisintech approved these changes Dec 9, 2024

View reviewed changes

victoriaxyz added 2 commits December 9, 2024 15:48

update sections

29d565c

fix link

aa8da0c

alexisintech reviewed Dec 9, 2024

View reviewed changes

Nikpolik force-pushed the nikpolik/user-1107-write-docs-on-how-to-enable-feature branch from 8eb549a to 7337b3e Compare December 10, 2024 09:03

Update attribute mapping section

07e1f1a

Nikpolik force-pushed the nikpolik/user-1107-write-docs-on-how-to-enable-feature branch from 7337b3e to 07e1f1a Compare December 10, 2024 09:06

Nikpolik and others added 2 commits December 10, 2024 13:37

Adjust steps to be grouped by the settings page

8f754cb

clean up instructions

6f2718e

alexisintech force-pushed the nikpolik/user-1107-write-docs-on-how-to-enable-feature branch from 1f2e03e to 6f2718e Compare December 10, 2024 15:57

alexisintech approved these changes Dec 10, 2024

View reviewed changes

Nikpolik merged commit f34168a into main Dec 11, 2024
4 checks passed

Nikpolik deleted the nikpolik/user-1107-write-docs-on-how-to-enable-feature branch December 11, 2024 08:52

royanger pushed a commit that referenced this pull request Dec 16, 2024

feat: Add docs for third party OIDC providers (#1769)

6cb3bb1

Co-authored-by: victoria <[email protected]> Co-authored-by: Alexis Aguilar <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add docs for third party OIDC providers #1769

feat: Add docs for third party OIDC providers #1769

Nikpolik commented Dec 4, 2024 •

edited by victoriaxyz

Loading

github-actions bot commented Dec 4, 2024

victoriaxyz Dec 5, 2024

victoriaxyz Dec 5, 2024

Nikpolik Dec 6, 2024 •

edited

Loading

victoriaxyz commented Dec 5, 2024

Nikpolik commented Dec 6, 2024

alexisintech left a comment

victoriaxyz commented Dec 9, 2024 •

edited

Loading

alexisintech Dec 9, 2024

Nikpolik Dec 10, 2024 •

edited

Loading

alexisintech Dec 9, 2024

alexisintech Dec 9, 2024

Nikpolik Dec 10, 2024

alexisintech Dec 9, 2024

alexisintech Dec 9, 2024

alexisintech Dec 9, 2024

Nikpolik Dec 10, 2024

alexisintech Dec 9, 2024

Nikpolik Dec 10, 2024

alexisintech Dec 10, 2024

alexisintech left a comment

	- If the IdPs that provide the value, enter `email_verified`.
	- If the IdP provides the value, enter `email_verified`.

		1. In the Clerk Dashboard, navigate to the Connection tab of the connection's settings page.
		1. In the Attribute Mapping section, under the Email address verified field:

	1. In the Clerk Dashboard, navigate to the Connection tab of the connection's settings page.
	1. In the Attribute Mapping section, under the Email address verified field:
	1. In the connection's settings page in the Clerk Dashboard, under Attribute Mapping, for the *Email address verified field:

	- For IdPs that do not provide the value, enter `xms_edov`.
	- If the IdP doesn't provide the value, enter `xms_edov`.

	> If the IdP doesn't return this claim, you can either leave the Email address verified field blank or set the Default value to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).
	> If the IdP doesn't return this claim, you can either leave the Email address verified field blank or set the Default value to True. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).

feat: Add docs for third party OIDC providers #1769

feat: Add docs for third party OIDC providers #1769

Conversation

Nikpolik commented Dec 4, 2024 • edited by victoriaxyz Loading

This PR:

Checklist

Note

github-actions bot commented Dec 4, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Nikpolik Dec 6, 2024 • edited Loading

Choose a reason for hiding this comment

victoriaxyz commented Dec 5, 2024

Nikpolik commented Dec 6, 2024

alexisintech left a comment

Choose a reason for hiding this comment

victoriaxyz commented Dec 9, 2024 • edited Loading

Choose a reason for hiding this comment

Nikpolik Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexisintech left a comment

Choose a reason for hiding this comment

Nikpolik commented Dec 4, 2024 •

edited by victoriaxyz

Loading

Nikpolik Dec 6, 2024 •

edited

Loading

victoriaxyz commented Dec 9, 2024 •

edited

Loading

Nikpolik Dec 10, 2024 •

edited

Loading